Hermes Agent config.yaml 完整参数详解

适用版本： Hermes Agent v0.12.0（2026.4.30）
文档说明： 基于真实生产环境 config.yaml，逐参数说明含义、作用域、默认值、注意事项。
配置路径： ~/.hermes/config.yaml

一、model — 主模型配置

model:
  default: MiniMax-M2.7-highspeed   # 主模型名称
  provider: minimax-cn              # 使用的 Provider 标识
  base_url: https://api.minimaxi.com/anthropic  # API 端点（⚠️ 切换 Provider 后应清空）
  name: MiniMax-M2.7-highspeed      # 模型名（与 default 通常相同）

参数	类型	默认值	说明
`default`	string	—	主用模型名称，即实际发给 LLM 的 `model` 参数
`provider`	string	—	Provider 标识，如 `minimax-cn`、`openrouter`、`anthropic` 等
`base_url`	string	—	API 请求目标地址。切换 Provider 后必须清空（设为空字符串），让系统自动使用 Provider 默认端点，否则会路由到旧地址导致 404/403
`name`	string	=default	模型名，等同于 `default`，存在是为了兼容两种写法

1.1 全局 Provider 配置（顶级）

providers: {}              # 各 Provider 的全局默认配置，目前通常为空
fallback_providers: []    # 主 Provider 失败时的备用 Provider 列表（未广泛使用）

1.2 凭证池策略

credential_pool_strategies:
  deepseek: fill_first    # DeepSeek：用完一个 Key 再用下一个
  minimax: fill_first     # MiniMax：同上

Key	取值	说明
`fill_first`	策略名	优先耗尽一个 API Key，再轮换到下一个
`round_robin`	策略名	均匀分配请求到所有 Key（需确认是否实现）

1.3 主工具集

toolsets:
  - hermes-cli           # Hermes 内置 CLI 工具（会话、配置、诊断等）

toolsets 声明的是全局默认工具集。平台级别可以在 platforms.*.toolsets 中单独覆盖。

二、agent — Agent 行为控制

agent:
  max_turns: 90                    # 单会话最大对话轮次（1次用户消息+1次LLM响应=1轮）
  gateway_timeout: 1800           # Gateway 模式下单任务超时（秒），超时后终止
  restart_drain_timeout: 60       # Gateway 重启前等待现有任务完成的超时（秒）
  api_max_retries: 3              # LLM API 调用失败时的最大重试次数
  service_tier: ''                 # 服务等级（部分 Provider 支持，如 anthropic）
  tool_use_enforcement: auto       # 强制使用工具：auto/always/never
  gateway_timeout_warning: 600     # 超时警告阈值（秒），达到后提醒用户
  gateway_auto_continue_freshness: 3600  # 自动续期 fresh 会话的时间（秒）
  image_input_mode: auto           # 图片输入模式：auto/force/vision_disabled
  disabled_toolsets: []            # 禁用的工具集列表（黑名单，优先级高于 toolsets）

参数	类型	默认值	说明
`max_turns`	int	90	防止无限循环，达到后强制结束会话
`gateway_timeout`	int	1800	Gateway 模式下任务最大运行时长（30分钟）
`restart_drain_timeout`	int	60	Gateway 重启时等待任务完成，超过后强制 kill
`api_max_retries`	int	3	网络/500错误时自动重试，用户限速错误不重试
`tool_use_enforcement`	enum	auto	`auto`=LLM自行决定，`always`=强制走工具，`never`=禁用工具
`gateway_timeout_warning`	int	600	任务运行 10 分钟后发警告（写入日志）
`gateway_auto_continue_freshness`	int	3600	fresh 状态的 Gateway 会话在 1 小时后自动续期
`image_input_mode`	enum	auto	`auto`=有图片自动用视觉模型，`force`=强制视觉，`vision_disabled`=禁用
`disabled_toolsets`	list	[]	强制禁用的工具集，即使在 toolsets 中声明了也不会加载

三、terminal — 终端执行环境

terminal:
  backend: local                   # 执行后端：local/docker/ssh/modal/singularity/daytona/vercel
  modal_mode: auto                 # Modal 部署模式：auto/legacy/native
  cwd: .                           # 默认工作目录（相对路径相对于 HERMES_HOME）
  timeout: 180                     # 单次命令执行超时（秒）
  env_passthrough: []              # 透传到 shell 的环境变量名列表（白名单）
  shell_init_files: []             # 启动时额外 source 的文件（如 ~/.bashrc_hermes）
  auto_source_bashrc: true         # 是否自动 source ~/.bashrc
  persistent_shell: true           # 是否复用同一个 shell 进程（⚠️ 设为 false 会每次都开新进程）

3.1 Docker 相关

  docker_image: nikolaik/python-nodejs:python3.11-nodejs20  # Docker 镜像
  docker_forward_env: []            # 从主机透传到容器的环境变量名列表
  docker_env: {}                    # 传给容器的额外环境变量（key: value 格式）
  docker_volumes: []                # 额外挂载卷：[ "host:container", ... ]
  docker_mount_cwd_to_workspace: false  # 是否把 cwd 挂载到容器内 /workspace
  docker_run_as_host_user: false    # 是否以主机用户 UID 运行（避免文件权限问题）

  singularity_image: docker://nikolaik/python-nodejs:python3.11-nodejs20
  modal_image: nikolaik/python-nodejs:python3.11-nodejs20
  daytona_image: nikolaik/python-nodejs:python3.11-nodejs20
  vercel_runtime: node24

3.3 容器资源限制

  container_cpu: 1                  # CPU 核心数
  container_memory: 5120            # 内存 MB
  container_disk: 51200             # 磁盘 MB
  container_persistent: true        # 容器是否持久化（不每次重建）

参数	类型	默认值	说明
`backend`	enum	local	`local`=本机 shell；`docker`=容器；`ssh`=远程；`modal`=Modal 云函数
`timeout`	int	180	单次终端命令超时，建议不要设太大防止僵尸命令
`persistent_shell`	bool	true	`true`=复用 shell（环境变量/cd 继承）；`false`=每次开新 shell
`auto_source_bashrc`	bool	true	是否自动执行 `source ~/.bashrc`（Linux 下常用）
`docker_mount_cwd_to_workspace`	bool	false	开启后当前工作目录内容在容器内可见，适合需要加载本地文件的场景

四、browser — 浏览器自动化

browser:
  inactivity_timeout: 120            # 无操作超时（秒），超时后关闭浏览器
  command_timeout: 30               # 单次浏览器命令超时（秒）
  record_sessions: false            # 是否录制浏览器会话视频
  allow_private_urls: false         # 是否允许访问私有IP（localhost/内网）
  auto_local_for_private_urls: true # 私有URL自动走本地浏览器（而非 CDP 云浏览器）
  cdp_url: ''                      # CDP 连接地址（为空则使用内置浏览器）
  dialog_policy: must_respond        # 对话框策略：must_respond/accept/dismiss
  dialog_timeout_s: 300             # 等待对话框操作超时
  camofox:                         # Camofox 云浏览器配置
    managed_persistence: false      # 是否开启会话持久化（云浏览器状态保持）

参数	类型	默认值	说明
`allow_private_urls`	bool	false	`true`=允许访问内网服务（如 `http://192.168.x.x`），有安全风险
`cdp_url`	string	''	填写则使用外部 CDP 端点（如 Browserbase），空则用本地 Chromium
`dialog_policy`	enum	must_respond	`must_respond`=必须AI处理对话框；`accept`=自动接受；`dismiss`=自动关闭

五、checkpoints — 文件系统快照

checkpoints:
  enabled: true                    # 是否开启文件系统快照
  max_snapshots: 50                # 最多保留快照数
  auto_prune: false                # 是否自动清理（超过 max 时）
  retention_days: 7                # 快照保留天数（auto_prune 时生效）
  delete_orphans: true             # 是否删除孤儿快照（无对应会话的快照）
  min_interval_hours: 24           # 两次快照最小间隔（小时）

参数	类型	默认值	说明
`enabled`	bool	true	开启后，每次工具调用前会打快照，回滚后可恢复
`auto_prune`	bool	false	设为 true 后自动删除超过 `max_snapshots` 或 `retention_days` 的快照
`delete_orphans`	bool	true	快照文件还在但对应会话已删除时，是否清理快照

六、file_read_max_chars — 文件读取上限

file_read_max_chars: 100000        # 单次 read_file 最多读取的字符数

超过此限制的文件会被截断，需用 offset+limit 参数分批读取。

七、tool_output — 工具输出截断

tool_output:
  max_bytes: 50000                 # 单个工具输出最大字节数
  max_lines: 2000                  # 最大行数
  max_line_length: 2000            # 单行最大字符数

参数	类型	默认值	说明
`max_bytes`	int	50000	工具返回结果超过此值会被截断（防止 token 溢出）
`max_lines`	int	2000	行数截断
`max_line_length`	int	2000	超过此宽度的行会被截断

八、tool_loop_guardrails — 工具循环防护

tool_loop_guardrails:
  warnings_enabled: true           # 是否启用警告
  hard_stop_enabled: false        # 是否启用硬停止（强制终止）
  warn_after:
    exact_failure: 2               # 同一工具连续失败 N 次后警告
    same_tool_failure: 3           # 同类工具连续失败 N 次后警告
    idempotent_no_progress: 2      # 幂等工具无进展连续 N 次后警告
  hard_stop_after:
    exact_failure: 5              # 同一工具失败 N 次后强制停止
    same_tool_failure: 8           # 同类工具失败 N 次后强制停止
    idempotent_no_progress: 5     # 幂等工具无进展 N 次后强制停止

参数	类型	默认值	说明
`exact_failure`	int	2/5	同一工具调用（如连续 2 次 `read_file` 都失败）
`same_tool_failure`	int	3/8	同类工具失败（如连续 3 次文件操作都失败）
`idempotent_no_progress`	int	2/5	幂等操作（read/search）重复调用但结果无变化
`hard_stop_enabled`	bool	false	设为 true 时，达到 `hard_stop_after` 阈值会强制终止会话

九、compression — 上下文压缩

compression:
  enabled: true                    # 是否启用上下文压缩
  threshold: 0.5                   # 触发压缩的 token 占比（0.0~1.0）
  target_ratio: 0.2               # 压缩后的目标 token 占比
  protect_last_n: 20               # 压缩时保留最近 N 条消息
  hygiene_hard_message_limit: 400  # 硬性消息数量上限（超过即强制压缩）

参数	类型	默认值	说明
`threshold`	float	0.5	当上下文占用 context window 的 50% 时触发压缩
`target_ratio`	float	0.2	压缩后希望剩余的比例（压缩掉 80%）
`protect_last_n`	int	20	压缩时保护最近 N 条消息不被删除
`hygiene_hard_message_limit`	int	400	消息数量超过此值时强制压缩（不管 token 比例）

9.1 prompt_caching

prompt_caching:
  cache_ttl: 5m                   # Prompt 缓存有效期（默认 5 分钟）

cache_ttl 控制重复系统提示的缓存时间，减少每次请求的 token 消耗。

十、bedrock — AWS Bedrock 配置（仅 AWS 环境）

bedrock:
  region: ''                       # AWS 区域
  discovery:
    enabled: true                 # 是否启用自动发现 Bedrock 模型
    provider_filter: []           # Provider 过滤列表
    refresh_interval: 3600        # 模型列表刷新间隔（秒）
  guardrail:
    guardrail_identifier: ''      # Guardrail 资源标识
    guardrail_version: ''         # Guardrail 版本
    stream_processing_mode: async # 流处理模式：async/sync
    trace: disabled               # 是否开启 trace

仅在使用 AWS Bedrock 作为模型提供商时需要配置。

十一、auxiliary — 辅助模型配置

auxiliary 是最重要的配置段落之一，用于配置各类辅助任务的模型（视觉、压缩、搜索等）。

auxiliary:
  vision:                         # 图片理解/视觉模型
    provider: auto                # 提供商：auto/minimax/openai/anthropic/google
    model: ''                     # 模型名（auto 时自动选择）
    base_url: ''                  # 自定义端点
    api_key: ''                   # API Key（通常用 .env 环境变量覆盖）
    timeout: 120                  # 请求超时（秒）
    extra_body: {}                # 额外 body 参数
    download_timeout: 30          # 图片下载超时

通用字段说明（适用于所有 auxiliary.* 子配置）：

字段	类型	默认值	说明
`provider`	enum	auto	`auto`=自动选择可用 provider；也可指定具体名称
`model`	string	''	指定模型名，留空则使用 provider 默认模型
`base_url`	string	''	覆盖默认 API 端点（用于代理/内网场景）
`api_key`	string	''	API Key（建议通过环境变量设置，不用明文）
`timeout`	int	见各配置	该辅助任务的超时时间
`extra_body`	dict	{}	额外传给 API 的 body 参数

11.1 各 auxiliary 子配置一览

子配置	用途	默认超时
`vision`	图片理解（vision_analyze / mcp_MiniMax_understand_image）	120s
`web_extract`	网页内容提取	360s
`compression`	上下文压缩（用于压缩模型）	120s
`session_search`	历史会话搜索	30s
`skills_hub`	Skills 市场搜索/发现	30s
`approval`	审批决策模型	30s
`mcp`	MCP 协议通信	30s
`title_generation`	会话标题生成	30s
`curator`	Skills 归档/整理	600s
`flush_memories`	记忆刷新	30s

⚠️ auxiliary 任务失败常见原因：auxiliary.* 的 provider 设为 auto 但没有配置任何有效 API Key（如只配了 OPENROUTER_API_KEY），自动选择失败。建议显式设置 provider 和 model。

十二、display — 界面显示控制

display:
  compact: false                  # 紧凑模式（减少空行）
  personality: kawaii             # 人格风格：default/kawaii/terse/assistant
  resume_display: full            # 恢复会话时显示内容：full/brief/none
  busy_input_mode: interrupt      # 忙碌时输入处理：interrupt/queue/ignore
  tui_auto_resume_recent: false   # 自动恢复最近会话（CLI TUI 模式）
  bell_on_complete: false         # 任务完成时响铃
  show_reasoning: false           # 是否在输出中显示推理过程
  streaming: false               # 是否流式显示输出
  final_response_markdown: strip  # 最终响应 markdown 处理：strip/preserve/raw
  inline_diffs: true              # patch 输出是否显示行内 diff
  show_cost: false                # 是否显示 token 消耗估算
  skin: default                   # TUI 主题皮肤
  tui_status_indicator: kaomoji   # TUI 状态指示器：kaomoji/text/blank
  user_message_preview:            # 用户消息预览设置
    first_lines: 2                # 开头显示几行
    last_lines: 2                 # 结尾显示几行
  interim_assistant_messages: true # 是否显示中间状态消息
  tool_progress_command: false    # 是否显示工具执行进度命令
  tool_progress_overrides: {}     # 工具进度覆盖（key=工具名，value=自定义文字）
  tool_preview_length: 0         # 工具预览长度（0=不限制）
  ephemeral_system_ttl: 0         # 临时系统消息 TTL（秒），0=不自动清除
  platforms: {}                   # 各平台的显示配置
  runtime_footer:                 # 底部状态栏
    enabled: false
    fields:                       # 显示字段：model/context_pct/cwd
      - model
      - context_pct
      - cwd
  tool_progress: all             # 工具进度显示模式：all/important/none

参数	类型	默认值	说明
`personality`	enum	kawaii	`kawaii`=可爱风格回复；`terse`=简洁；`assistant`=助手风格
`show_reasoning`	bool	false	设为 true 可在输出中看到模型思考过程（会显著增加 token 消耗）
`streaming`	bool	false	流式输出，AI边生成边显示（CLI 常用）
`final_response_markdown`	enum	strip	`strip`=去除 markdown 格式；`preserve`=保留；`raw`=原始输出
`inline_diffs`	bool	true	patch 工具输出时显示删减行（`-`红色/+绿色）
`show_cost`	bool	false	设为 true 在响应末尾显示本次 token 消耗

十三、dashboard — Web Dashboard 配置

dashboard:
  theme: default                  # Dashboard 主题

Dashboard 是 Hermes 的 Web 监控界面，访问通常通过 hermes dashboard 命令启动。

十四、privacy — 隐私控制

privacy:
  redact_pii: false              # 是否自动脱敏 PII（人名/手机号/身份证等）

⚠️ redact_pii 开启后，消息中的敏感信息会被替换为 [REDACTED]，会影响功能，谨慎开启。

十五、tts — 文字转语音

tts:
  provider: edge                 # TTS 提供商：edge/elevenlabs/openai/xai/mistral/neutts/piper/minimax

子配置块	适用 provider	说明
`edge`	edge	微软 Edge TTS，免费，支持中文，选 `zh-CN-XiaoxiaoNeural`
`elevenlabs`	elevenlabs	商业付费，音色克隆强
`openai`	openai	OpenAI TTS
`xai`	xai	xAI Grok TTS
`mistral`	mistral	Mistral Voxtral TTS
`neutts`	neutts	本地免费 TTS，需安装 `neutts[all]` + `espeak-ng`
`piper`	piper	本地 TTS
`minimax`	minimax	MiniMax TTS（当前配置使用这个）

15.1 minimax TTS 子配置

  minimax:
    model: speech-2.8-hd         # MiniMax TTS 模型
    voice_id: female-tianmei     # 音色 ID
    base_url: https://api.minimax.chat/v1/t2a_v2  # TTS API 端点

十六、stt — 语音转文字

stt:
  enabled: true                  # 是否启用语音转文字
  provider: local                # 提供商：local（faster-whisper）/openai/mistral
  local:
    model: base                  # whisper 模型大小：tiny/base/small/medium/large-v3
    language: ''                 # 语言（留空则自动检测）
  openai:
    model: whisper-1
  mistral:
    model: voxtral-mini-latest

参数	类型	默认值	说明
`provider`	enum	local	`local`=本地运行 faster-whisper（推荐，免费）；`openai`=用 OpenAI Whisper API；`mistral`=Mistral
`local.model`	enum	base	本地 whisper 模型大小，越大越准但越慢，Mac M系列推荐 `small`

十七、voice — 语音交互控制

voice:
  record_key: ctrl+b            # 按键开始录音（Linux TUI 快捷键）
  max_recording_seconds: 120    # 单次最大录音时长（秒）
  auto_tts: false               # 是否自动将 AI 响应转为语音
  beep_enabled: true             # 录音开始/结束时的提示音
  silence_threshold: 200        # 静音检测阈值（音频强度）
  silence_duration: 3.0          # 超过此秒数的静音自动停止录音

参数	类型	默认值	说明
`record_key`	string	ctrl+b	按住此键说话（Linux ncurses 格式，`ctrl+b` 等于 Ctrl+B）
`auto_tts`	bool	false	`true`=AI 每次回复自动 TTS 播放声音
`silence_threshold`	int	200	低于此音频强度认为是静音（0~32767范围）
`silence_duration`	float	3.0	静音持续超过此秒数自动停止录音

十八、human_delay — 人工延迟模拟

human_delay:
  mode: 'off'                  # 模式：off/on/random
  min_ms: 800                  # 最小延迟（毫秒）
  max_ms: 2500                 # 最大延迟（毫秒）

mode: on 时，每次 AI 响应后会等待 min_ms~max_ms 毫秒再显示，模拟人工输入延迟，用于演示/教学。

十九、context — 上下文引擎

context:
  engine: compressor             # 上下文引擎：compressor（压缩）/ naive（原始）

当前只有 compressor 一种实现，通过 LLM 压缩历史消息。

二十、memory — 记忆系统

memory:
  memory_enabled: true           # 是否启用跨会话记忆
  user_profile_enabled: true    # 是否启用用户画像（存储用户偏好）
  memory_char_limit: 2200       # 单条记忆最大字符数
  user_char_limit: 1375         # 用户画像最大字符数
  provider: ''                  # 记忆 Provider：空=内置/ honcho/ mem0

参数	类型	默认值	说明
`memory_enabled`	bool	true	设为 false 关闭跨会话记忆功能
`user_profile_enabled`	bool	true	存储用户信息（姓名/偏好/习惯）
`memory_char_limit`	int	2200	单条记忆内容最大长度
`provider`	string	''	空=内置记忆系统；`honcho`=Honcho 外置记忆；`mem0`=Mem0

二十一、delegation — 子 Agent 委托

delegation:
  model: ''                     # 子 Agent 使用的主模型（空则继承主模型）
  provider: ''                  # 子 Agent Provider（空则继承）
  base_url: ''                  # 自定义 base_url
  api_key: ''                   # 自定义 api_key
  inherit_mcp_toolsets: true   # 子 Agent 是否继承 MCP 工具集
  max_iterations: 50            # 子 Agent 最大迭代次数
  child_timeout_seconds: 600    # 子 Agent 单次任务超时（10分钟）
  reasoning_effort: ''          # 推理强度：low/medium/high（空=继承主模型设置）
  max_concurrent_children: 5    # 并行子 Agent 最大数量
  max_spawn_depth: 1            # 嵌套深度：1=flat/2=可嵌套/3=三层
  orchestrator_enabled: true   # 是否允许 Orchestrator 角色（可嵌套派生）
  subagent_auto_approve: false # 子 Agent 是否自动批准危险操作

参数	类型	默认值	说明
`max_concurrent_children`	int	5	`delegate_task` 并行批次中的最大子 Agent 数
`max_spawn_depth`	int	1	嵌套深度：1=叶子模式（不可派生）；2=可嵌套一层；3=可嵌套两层
`orchestrator_enabled`	bool	true	设为 false 则即使 `max_spawn_depth>1` 也不允许 orchestrator 角色
`subagent_auto_approve`	bool	false	危险操作（删除/格式化等）是否需要主 Agent 确认

二十二、prefill_messages_file — 预填充消息

prefill_messages_file: ''       # 启动时自动注入的消息文件路径（JSONL格式）

填入文件路径后，Hermes 启动时会从该文件读取消息并注入到上下文中，用于初始化上下文或调试。

二十三、goals — Goals 模式配置

goals:
  max_turns: 20                 # Goals 模式下最大轮次

Goals 是 Hermes 的一种特殊会话模式，通常用于多目标追踪的任务。

二十四、skills — Skills 系统配置

skills:
  external_dirs: []              # 额外技能目录（扫描 SKILL.md 的额外路径）
  template_vars: true            # 是否支持 Jinja2 模板变量
  inline_shell: false            # 是否允许内联 shell 技能
  inline_shell_timeout: 10      # 内联 shell 超时（秒）
  guard_agent_created: false    # 是否对 AI 创建的技能启用 guard

参数	类型	默认值	说明
`external_dirs`	list	[]	额外的技能目录，如 `['/mnt/skills', '~/my-skills']`
`template_vars`	bool	true	技能模板中是否支持 `{{ user_name }}` 等 Jinja2 变量
`inline_shell`	bool	false	是否允许直接在技能中写 shell 脚本

二十五、curator — Skills 自动整理

curator:
  enabled: true                  # 是否启用自动整理
  interval_hours: 168            # 整理周期（7天）
  min_idle_hours: 2             # 距上次使用少于 N 小时才整理
  stale_after_days: 30          # 超过 N 天未使用标记为过时
  archive_after_days: 90        # 超过 N 天自动归档
  backup:
    enabled: true               # 归档前是否备份
    keep: 5                      # 最多保留 N 个备份

参数	类型	默认值	说明
`enabled`	bool	true	关闭后 curator 不会自动运行
`interval_hours`	int	168	每 7 天检查一次技能状态
`stale_after_days`	int	30	30 天未使用的技能标记为过时
`archive_after_days`	int	90	90 天未使用则归档（从主动加载列表移除）

二十六、honcho — Honcho 记忆集成

honcho: {}                       # Honcho 外置记忆服务的配置（目前为空）

honcho 是 Hermes 的可选外置记忆服务，需要额外安装和配置。

二十七、timezone — 时区设置

timezone: ''                     # 时区（空=系统默认，如 Asia/Shanghai）

影响日志时间戳和定时任务的执行时间。设为空字符串则使用服务器系统时区。

二十八、平台配置（discord / whatsapp / telegram / slack / mattermost）

discord:
  require_mention: true          # 是否必须 @机器人 才响应
  free_response_channels: ''    # 允许自由响应（不需@）的频道 ID 列表
  allowed_channels: ''          # 允许的频道 ID（白名单）
  auto_thread: true             # 是否自动为新对话创建线程
  reactions: true               # 是否对消息添加 reactions
  channel_prompts: {}           # 各频道的个性化提示词
  server_actions: ''             # 服务级别操作配置

各平台通用字段说明：

参数	类型	说明
`require_mention`	bool	`true`=只有 @机器人才响应；`false`=所有消息都响应
`auto_thread`	bool	`true`=自动在频道下创建 thread 隔离对话
`channel_prompts`	dict	以 channel_id 为 key，定义该频道的系统提示词
`reactions`	bool	是否在 AI 响应时添加表情回应

二十九、approvals — 审批/危险操作确认

approvals:
  mode: manual                  # 审批模式：manual/auto/deny
  timeout: 60                   # 审批等待超时（秒），超时视为拒绝
  cron_mode: deny               # Cron 任务审批模式：deny/auto/manual
  mcp_reload_confirm: true      # MCP 重载是否需要确认

参数	类型	默认值	说明
`mode`	enum	manual	`manual`=每次危险操作需确认；`auto`=自动批准；`deny`=自动拒绝
`timeout`	int	60	用户在 N 秒内未审批则视为超时
`cron_mode`	enum	deny	Cron 任务中危险操作的默认行为

三十、command_allowlist — 危险命令白名单

command_allowlist:
  - script execution via heredoc          # 脚本通过 heredoc 执行
  - recursive delete                      # 递归删除（rm -rf）
  - disk copy                             # 磁盘复制命令
  - overwrite system config                # 覆盖系统配置
  - delete in root path                   # 在根目录删除
  - start gateway outside systemd          # 非 systemd 启动 gateway
  - kill hermes/gateway process           # 终止 hermes/gateway 进程
  - shell command via -c/-lc flag          # 通过 -c/-lc 执行命令
  - script execution via -e/-c flag       # 通过 -e/-c 执行脚本
  - stop/restart system service           # 停止/重启系统服务
  - SQL DELETE without WHERE               # 无 WHERE 条件的 DELETE
  - force kill processes                  # 强制终止进程
  - hermes update                         # hermes update（会重启 gateway）
  - copy/move file into /etc/             # 复制/移动文件到 /etc/
  - overwrite system file via redirection  # 通过重定向覆盖系统文件
  - stop/restart hermes gateway           # 停止/重启 hermes gateway
  - pipe remote content to shell          # 将远程内容管道到 shell

command_allowlist 中的条目定义了需要 approvals 审批才能执行的命令类别。空列表=不限制。

三十一、quick_commands — 快捷命令别名

quick_commands: {}               # 快捷命令映射：key=触发词，value=实际命令
hooks: {}                       # 生命周期钩子（key=事件名，value=脚本路径）
hooks_auto_accept: false         # 钩子脚本是否自动批准
personalities: {}               # 自定义人格配置

参数	类型	说明
`quick_commands`	dict	如 `{"gc": "hermes git commit -v"}`，用户输入 `/gc` 则执行对应命令
`hooks`	dict	生命周期钩子，如 `{session_start: /path/to/script.sh}`
`hooks_auto_accept`	bool	设为 true 则钩子脚本执行不需要确认

三十二、security — 安全策略

security:
  allow_private_urls: false      # 是否允许访问私有 URL
  redact_secrets: true           # 是否在日志中脱敏 API Key
  tirith_enabled: true           # 是否启用 Tirith 内容安全过滤
  tirith_path: tirith            # Tirith 规则文件路径
  tirith_timeout: 5              # Tirith 过滤超时（秒）
  tirith_fail_open: true         # Tirith 超时时是否放行（false=拒绝）
  website_blocklist:
    enabled: false               # 是否启用网站黑名单
    domains: []                  # 黑名单域名列表
    shared_files: []             # 共享文件限制列表

参数	类型	默认值	说明
`redact_secrets`	bool	true	日志中自动将 `sk-xxx`、`sk_cp_xxx` 等 Key 脱敏为 `sk_***`
`tirth_enabled`	bool	true	Tirith 是 Hermes 的内容安全/恶意提示检测模块
`tirth_fail_open`	bool	true	`true`=Tirith 超时/失败时放行；`false`=视为不安全并拒绝

三十三、cron — 定时任务配置

cron:
  wrap_response: true            # 响应是否包裹格式（HTML/markdown）
  max_parallel_jobs: null        # 最大并行任务数（null=无限制）

参数	类型	说明
`wrap_response`	bool	`true`=cron 输出包裹为 HTML；`false`=纯文本
`max_parallel_jobs`	int/null	最大同时运行的 cron 任务数，null=无限制

三十四、kanban — 看板任务调度

kanban:
  dispatch_in_gateway: true     # 是否在 Gateway 进程中分发任务
  dispatch_interval_seconds: 60 # 任务分发检查间隔（秒）

看板功能用于多任务调度追踪，dispatch_in_gateway: true 表示在 Gateway 主循环中处理。

三十五、code_execution — 代码执行模式

code_execution:
  mode: project                 # 代码执行模式：project/sandbox/isolated

取值	说明
`project`	项目模式，可访问工作目录
`sandbox`	沙箱模式，限制文件系统和网络访问
`isolated`	完全隔离，独立环境

三十六、logging — 日志配置

logging:
  level: INFO                  # 日志级别：DEBUG/INFO/WARNING/ERROR
  max_size_mb: 5               # 单个日志文件最大大小（MB）
  backup_count: 3               # 保留的旧日志文件数量

参数	类型	默认值	说明
`level`	enum	INFO	`DEBUG`=最详细；`INFO`=一般信息；`WARNING`=警告；`ERROR`=只记录错误
`max_size_mb`	int	5	日志文件超过此大小自动轮转
`backup_count`	int	3	保留 N 个旧日志文件

三十七、model_catalog — 模型目录

model_catalog:
  enabled: true                # 是否启用模型目录
  url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
  ttl_hours: 24               # 模型目录缓存 TTL（小时）
  providers: {}                # 各 Provider 的模型列表覆盖

model_catalog 从远程 URL 获取可用模型列表，本地缓存 24 小时。

三十八、network — 网络配置

network:
  force_ipv4: false            # 是否强制使用 IPv4

force_ipv4: true 用于某些只支持 IPv4 的网络环境。

三十九、sessions — 会话管理

sessions:
  auto_prune: false            # 是否自动清理旧会话
  retention_days: 90           # 会话保留天数
  vacuum_after_prune: true     # 清理后是否 VACUUM 数据库（减少文件大小）
  min_interval_hours: 24       # 两次自动清理最小间隔

参数	类型	默认值	说明
`auto_prune`	bool	false	设为 true 后自动删除超过 `retention_days` 的会话
`vacuum_after_prune`	bool	true	SQLite 删除数据后执行 VACUUM 回收空间
`retention_days`	int	90	超过此天数的会话在 auto_prune 时被删除

四十、onboarding — 新手引导

onboarding:
  seen:                        # 已完成的新手引导步骤
    busy_input_prompt: true    # 忙碌时输入提示
    openclaw_residue_cleanup: true  # OpenClaw 残留清理

用户完成某个引导步骤后，对应 key 设为 true，下次不再显示。

四十一、updates — 自动更新配置

updates:
  pre_update_backup: false     # 更新前是否备份
  backup_keep: 5               # 最多保留 N 个备份

四十二、_config_version — 配置版本

_config_version: 23            # 配置文件格式版本（勿手动修改）

Hermes 内部用于追踪 config.yaml 的格式版本，自动更新，勿手动修改。

四十三、smart_model_routing — 智能模型路由

smart_model_routing:
  enabled: false               # 是否启用智能路由
  max_simple_chars: 160        # 简单任务字符数阈值
  max_simple_words: 28         # 简单任务词数阈值
  cheap_model: {}              # 便宜模型配置（用于简单任务自动降级）

smart_model_routing: enabled: true 时，Hermes 会自动判断任务复杂度，简单任务用便宜模型省成本。

四十四、platforms — 平台配置

platforms:
  wecom:
    enabled: true
    home_channel:
      platform: wecom
      chat_id: aiden
      name: Home
    extra:
      bot_id: aibwIiK6DMMEGVyqXp3zWENamUXDDP5_Vin
      secret: **已脱敏**
      websocket_url: wss://openws.work.weixin.qq.com
      dm_policy: open
      group_policy: open

参数	类型	说明
`home_channel`	object	默认发送目标，`chat_id` 对应企业微信的 user_id
`extra.bot_id`	string	企业微信机器人 AppID
`extra.secret`	string	企业微信机器人 Secret
`extra.websocket_url`	string	企业微信 WebSocket 长连接地址
`extra.dm_policy`	enum	私信策略：`open`=允许，`member_only`=仅成员
`extra.group_policy`	enum	群策略：`open`=允许，`member_only`=仅成员

四十五、mcp_servers — MCP 服务器配置

mcp_servers:
  MiniMax:                     # MCP 服务器名称
    command: uvx               # 启动命令（uvx = uv run execute）
    args:                      # 传给命令的参数
      - minimax-coding-plan-mcp
      - -y
    env:                       # 环境变量
      MINIMAX_API_KEY: sk-cp-...y9LA   # 已脱敏
      MINIMAX_API_HOST: https://api.minimaxi.com
    timeout: 120              # MCP 请求超时
    connect_timeout: 60       # 连接超时

参数	类型	说明
`command`	string	启动命令（`uvx`/`python`/`node`等）
`args`	list	命令行参数
`env`	dict	传给进程的环境变量（可引用 `~/.hermes/.env` 中的变量）
`timeout`	int	单次 MCP 调用超时
`connect_timeout`	int	建立连接超时

四十六、session_reset — 会话自动重置

session_reset:
  mode: both                  # 重置模式：idle/both/absolute
  idle_minutes: 1440          # 空闲 N 分钟后重置（1440=24小时）
  at_hour: 4                  # 每天固定时间重置（凌晨4点）

参数	类型	说明
`mode`	enum	`idle`=仅空闲超时；`both`=空闲超时+每日定时；`absolute`=仅每日定时
`idle_minutes`	int	超过此分钟数无活动则重置
`at_hour`	int	每天 UTC 几点点重置（`4` = 凌晨4点）

四十七、plugins — 插件管理

plugins:
  enabled: []                 # 启用的插件列表

填写插件名称（如 honcho），对应的插件必须已安装在 ~/.hermes/plugins/ 目录下。

四十八、fallback_model — 备用模型

fallback_model:
  provider: deepseek          # 备用 Provider
  model: deepseek-v4-flash    # 备用模型名

主模型不可用（如 API Key 耗尽/网络错误）时，自动切换到备用模型。

四十九、Provider 专用配置块

minimax-cn:                   # minimax-cn Provider 的专用配置
  api_key: sk-cp-...y9LA     # 该 Provider 的 API Key（已脱敏）

格式为 {provider_name}: {api_key: ...}，每个 Provider 可以有自己的专用配置块，优先级高于 .env 环境变量。

附录：Provider 默认 Base URL 参考

Provider	默认 Base URL	Env var override
`deepseek`	`https://api.deepseek.com/v1`	`DEEPSEEK_BASE_URL`
`minimax-cn`	`https://api.minimaxi.com/anthropic`	`MINIMAX_CN_BASE_URL`
`minimax` (global)	`https://api.minimaxi.com/v1`	`MINIMAX_BASE_URL`
`openrouter`	`https://openrouter.ai/api/v1`	`OPENROUTER_BASE_URL`
`anthropic`	`https://api.anthropic.com`	`ANTHROPIC_API_KEY`
`google`/`gemini`	`https://generativelanguage.googleapis.com/v1beta/openai/`	`GOOGLE_API_BASE`
`openai`	`https://api.openai.com/v1`	`OPENAI_BASE_URL`
`kimi`/`moonshot`	`https://api.moonshot.cn/v1`	`KIMI_BASE_URL`
`dashscope`/`alibaba`	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`DASHSCOPE_BASE_URL`
`mistral`	`https://api.mistral.ai/v1`	`MISTRAL_BASE_URL`

⚠️ 重要：切换 Provider 后，必须执行 hermes config set model.base_url '' 清空 base_url，否则请求会发到旧的端点。

附录：配置段落后优先级总结

命令行参数（最高）
  > 环境变量（~/.hermes/.env）
    > config.yaml 中的 provider 专用块（如 minimax-cn:）
      > config.yaml 顶级配置
        > 默认值（最低）

文档基于 Hermes Agent v0.12.0 实际配置文件分析整理，如有参数与新版本不符请以官方文档为准。
*官方配置参考：https://hermes-agent.nousresearch.com/docs/user-guide/configuration*